Authorization Server Installation (COMPASS 6.2)

Introduction

The REST Services in COMPASS can be secured via OAuth2 against unauthorized access. This document describes the necessary steps to protect the REST-API via OAuth2 against unauthorized access. Please keep in mind that COMPASS also can be secured using alternative mechanisms such as KEYCLOAK or by adapting the Deployment Descriptor (web.xml), which is not part of this document.

COMPASS components which can be secured with COMPASS' implementation of OAUTH2 Authorization Server currently is only the RuleManagerApp together with RuleManagerService. If a COMPASS customers want to implement their own Screenbuilder Client, they may also secure access by using OAuth2 wíth COMPASS' Authorization Server.

However, since from on version 6.2, COMPASS fully supports being secured via KEYCLOAK which his highly recommended by Gen Re.

OAuth2

OAuth2 provides a secure, reliable and efficient communication between client and server applications without the need to exchange Authorization information (user/password) with every request. For this purpose, it relies on the OAuth (Open Authorization)-Technology. OAuth is an open, token-based protocol that enables a standardised and secure API Authorization. At the moment there are two versions of this protocol: OAuth 1.0 (RFC 5849) and OAuth 2.0 (RFC 6749). This document focuses on Version 2.0, which is being referred to as OAuth2.

OAuth2 defines the following roles of users and applications:

Resource Owner – entity (i.e. the user) that owns a resource on the resource server. The Resouce Owner wants to allow the Client access to these resources
Resource Server – server that hosts the secured resources of the Resource Owner. It checks access privileges by checking received tokens
Client – application that wants to access secured resources. To access these resources, it must be authorised by the Resource Owner.
Authorization Server – server that performs the authorization of the Resource Owner which returns a token to the Client if authorization was successful.

General Flow:

Figure 1. General Flow

Abstract OAuth2 protocol flow:

Start: the Client wants access to some resources of the user that are lying in the Resource Server.

Authorization request: the Client sends the authorization question to the user
Authorization/Refusal: the User allows or refuses access to the Resource Server.
Authorization forwarding: the Client sends the access data (its own and the user’s) to the Authorization Server
Token-Response: the Authorization Server checks the access data. Generates the access token and returns it to the Client
Resource request: the Client uses the access token and sends the request to the Resource Server
Resource response: the Resource Server checks the access token on validity and authority. If approved, it generates the requested resource, and sends it back to the Client application

In OAuth2, a token contains important information required for the Authentication and Authorization mechanism. There are two kinds of tokens:

Access Token – generated by the Authorization Server as a result of a successful authentication, and sent back to the Client application. The access token contains a scope parameter that is used to restrict / grant access. The access token usually has a limited period of validity.

Refresh Token – also generated by the Authorization Server, is being used to request a new access token once the old access token has expired. The refresh token also represents the authorization of the Resource Owner, and as such no new authorization is required. The refresh token can also have a limited period of validity. Obviously, refresh tokens should time out only after the corresponding access tokens time out.

The following terms are being used in the next chapters:

resource-id – Name or ID of the resource that should be protected from unauthorised access
client-id/client-secret – access information for the Client application
username/password – access information of the user that allows access to its resources
authorized_grant_types – authorization types, i.e. the type of authorization allowed. OAuth2 offers 5 types: authorization_code, client_credentials, password, refresh_token and implicit. In this documentation we will only encounter password and refresh_token
scope – the scope of permission for the Client application. This value(s) can be defined freely, but are typically read or write
authority – the access permission for the user within the scope. Values can be defined freely
access_token_validity – Validity of the access token in seconds
refresh_token_validity – Validity of the refresh token in seconds. Should be longer than the value of the corresponding access token

OAuth2 used by the COMPASS / RuleManager REST API

The OAuth2-solution for the COMPASS / RuleManager REST API uses only a part of the possibilities described above.

The main issue is that there is only one technical user, and therefore the resources are not user-specific: the Client (i.e. CompassService or RuleManagerService) either get access to all resources or no access at all. As such, steps ① and ② of the picture in OAuth2 are omitted. Furthermore, no AUTHORITY has been defined, and only a default Dummy AUTHORITY is used and required.

This solution therefore only uses the OAuth2 mechanisms of access- and refresh tokens.

As steps ① and ② are omitted, the authorization data of the “user” can’t be requested from the user, instead it is read from a property file (i.e, CompassService.properties or RulemanagerService.properties).

This leads to a simplified picture in analogy to the one in chapter OAuth2: the Resource Owner is omitted, i.e. authorization is done implicitly.

The following 3 roles remain:

Resource Server – the server that hosts the secured resources. It checks access privileges by checking received tokens. This is in fact the COMPASS / RuleManager REST Service.
Client – an application that wants to access secured resources of the Resource Server. This can be any Client that wants to access COMPASS / RuleManager REST Service. As an example, we have built the CaseViewerApp and RuleManagerApp_ in such a way, that access to COMPASS / RuleManager REST Services is secured via OAuth2 being provided by COMPASS' Authorization Server.
Authorization Server – the server that performs the Authorization of the default Resource Owner, and who returns a token to the Client when the authorization was successful.

Example: Information flow with RuleManagerApp

As an example, below the particular information flow is depicted for the RuleManagerApp:

Figure 2. Information flow with RuleManagerApp

Example: Compass-REST security with RuleManagerApp

To protect the COMPASS REST Services, the following model has been designed:

Figure 3. Authentication- / Authorization-Flow

Each COMPASS user starts a RuleManager session providing their credentials to the RuleManagerApp which forwards it to the Authorization Server
Authorization Server checks the credentials against the User DB and, if valid, provides an Access token, returning the token to RuleManagerApp
RuleManagerApp provides the token together with the request to RuleManager-Service, which provides the token again to Authorization Service to check it’s validity.
If the token is valid, RuleManagerService acesses the Resource DB and returns the resource requested to the RuleManagerApp The implementation of the authorization mechanism is based on the Spring-Boot Framework. It makes use of framework libraries like Spring-Boot-Security and Spring- Security-OAuth2.

The following components are part of the possible deployment of COMPASS (compare with diagram above):

RuleManagerApp.war`:
Frontend, Angular based
RuleManagerService.war or RuleManagerService.jar:
Provides functionality to access required resources of the resource owner, based on Spring Boot
AuthorizationServer.war or AuthorizationServer.jar:
Provides functionality to check whether RuleManagerService’s access to requested resources is valid

Installation

Installing the database layer

The authorization mechanism exchanges and compares data between Authorization Server, Compass- or RuleManager-Service and the client program (i.e. RuleManagerApp). This data can be grouped into three categories: Tokens, information about client applications and user data. For consistency reasons, we suggest storing all data in one central database. The data is stored in 5 tables:

Two tables for the tokens:
1. oauth_access_token
2. oauth_refresh_token
One table for the Client data:
1. oauth_client_details
Two tables for the user administration:
1. users
2. authorities

In this chapter, the tables are presented one by one. Please consider that all data types for the columns correspond to the MySQL syntax. DDL for MS-SQL Server, MySQL, Oracle and DB2 databases are provided in the subchapters.

Table oauth_access_token: stores the access tokens, as soon as the user has been authorised by his access data and the client’s access information. One row contains the access token, Client-ID, user name, access rights, scope, as well as a reference to the refresh token. The handling of this table is under OAuth control, i.e. the Authorization Server.

token_id			    VARCHAR(255)		NOT NULL,
token				    mediumblob		    NOT NULL,
authentication_id 		VARCHAR(255) 		NOT NULL,
user_name 			    VARCHAR(255)		NOT NULL,
client_id 			    VARCHAR(255)		NOT NULL,
authentication 		    mediumblob		    NOT NULL,
refresh_token 		    VARCHAR(255)		NOT NULL

Table oauth_refresh_token: stores the refresh token, which is generated and inserted automatically and in parallel to the access token. One row contains basically the refresh token itself, which is used to generate a new access token, once the previous one has expired. To create a new access token based on the refresh token, there is no need to pass the credentials and user/password combinations of the user again. The handling of this table is under OAuth control, i.e. the Authorization Server.

token_id 			VARCHAR(255)		NOT NULL,
token 				mediumblob		    NOT NULL,
authentication 		mediumblob		    NOT NULL

Table oauth_client_details: contains the access information for client applications (client-name and corresponding password) in the columns client_id and client_secret. It also contains additional information about the resources, which can be accessed, information about privileges and scopes, type of authentication, optional the redirect-URL, validity of access and refresh tokens, etc. This table is prefilled by the administrator (see Authorization data in the database):

client_id 		        	VARCHAR(256) 		NOT NULL,
client_secret			    VARCHAR(256)		NOT NULL,
resource_ids 			    VARCHAR(256)		NOT NULL,
scope 				        VARCHAR(256)		NULL,
authorized_grant_types 	    VARCHAR(256)		NOT NULL,
web_server_redirect_uri 	VARCHAR(256)		NULL,
authorities 			    VARCHAR(256)		NULL,
access_token_validity  	    INT(11)		        NULL,
refresh_token_validity 	    INT(11)		        NULL,
additional_information 	    VARCHAR(4096)		NULL,
autoapprove 			    VARCHAR(256)		NULL

Table users: contains user/password access combinations with the flag whether the user is active of not. This table is prefilled by the administrator (see Authorization data in the database):

username 			VARCHAR(50) 		NOT NULL,
password 			VARCHAR(500) 		NOT NULL,
enabled	 		    SMALLINT     		NOT NULL

Table authorities: contains a reference to a user and the authority within its scope. This table is prefilled by the administrator (see Authorization data in the database):

username			VARCHAR(50) 		NOT NULL,
authority			VARCHAR(50) 		NOT NULL

SQL-Create for MySQL

CREATE TABLE oauth_access_token (
    token_id VARCHAR(255) NOT NULL,
    token mediumblob NOT NULL,
    authentication_id VARCHAR(255) NOT NULL,
    user_name VARCHAR(255) NOT NULL,
    client_id VARCHAR(255) NOT NULL,
    authentication mediumblob NOT NULL,
    refresh_token VARCHAR(255) NOT NULL,
    PRIMARY KEY (authentication_id)
);
CREATE TABLE oauth_refresh_token (
    token_id VARCHAR(255) NOT NULL,
    token mediumblob NOT NULL,
    authentication mediumblob NOT NULL
);
CREATE TABLE oauth_client_details (
    client_id VARCHAR(256) NOT NULL,
    resource_ids VARCHAR(256) NOT NULL,
    client_secret VARCHAR(256) NOT NULL,
    scope VARCHAR(256) NULL,
    authorized_grant_types VARCHAR(256) NOT NULL,
    web_server_redirect_uri VARCHAR(256) NULL,
    authorities VARCHAR(256) NULL,
    access_token_validity INT NULL,
    refresh_token_validity INT NULL,
    additional_information VARCHAR(4096) NULL,
    autoapprove VARCHAR(256) NULL,
    PRIMARY KEY (client_id)
);
CREATE TABLE users (
    USERNAME VARCHAR(50) NOT NULL,
    PASSWORD VARCHAR(500) NOT NULL,
    ENABLED TINYINT(1) NOT NULL,
    PRIMARY KEY (USERNAME)
);
CREATE TABLE authorities (
    USERNAME VARCHAR(50) NOT NULL,
    AUTHORITY VARCHAR(50) NOT NULL,
    CONSTRAINT USERS_AUTHORITIES FOREIGN KEY (USERNAME) REFERENCES users (USERNAME),
    CONSTRAINT AUTH_USERNAME UNIQUE (USERNAME, AUTHORITY)
);

SQL-Create for Oracle

CREATE TABLE oauth_access_token (
    token_id VARCHAR(255) NOT NULL,
    token blob NOT NULL,
    authentication_id VARCHAR(255) NOT NULL,
    user_name VARCHAR(50) NOT NULL,
    client_id VARCHAR(255) NOT NULL,
    authentication blob NOT NULL,
    refresh_token VARCHAR(255) NOT NULL,
    PRIMARY KEY (authentication_id)
);
CREATE TABLE oauth_refresh_token (
    token_id VARCHAR(255) NOT NULL,
    token blob NOT NULL,
    authentication blob NOT NULL
);
CREATE TABLE oauth_client_details (
    client_id VARCHAR(256) NOT NULL,
    resource_ids VARCHAR(256) NOT NULL,
    client_secret VARCHAR(256) NOT NULL,
    scope VARCHAR(256) NULL,
    authorized_grant_types VARCHAR(256) NOT NULL,
    web_server_redirect_uri VARCHAR(256) NULL,
    authorities VARCHAR(256) NULL,
    access_token_validity INT NULL,
    refresh_token_validity INT NULL,
    additional_information VARCHAR(4096) NULL,
    autoapprove VARCHAR(256) NULL,
    PRIMARY KEY (client_id)
);
CREATE TABLE users (
    USERNAME VARCHAR(50) NOT NULL,
    PASSWORD VARCHAR(500) NOT NULL,
    ENABLED NUMBER(1) NOT NULL,
    PRIMARY KEY (USERNAME)
);
CREATE TABLE authorities (
    USERNAME VARCHAR(50) NOT NULL,
    AUTHORITY VARCHAR(50) NOT NULL,
    CONSTRAINT USERS_AUTHORITIES FOREIGN KEY (USERNAME) REFERENCES users (USERNAME),
    CONSTRAINT AUTH_USERNAME UNIQUE (USERNAME, AUTHORITY)
);

SQL-Create for MS-SQL Server

CREATE TABLE oauth_access_token (
  token_id VARCHAR(255) NOT NULL,
  token varbinary(max) NOT NULL,
  authentication_id VARCHAR(255) NOT NULL,
  user_name VARCHAR(255) NOT NULL,
  client_id VARCHAR(255) NOT NULL,
  authentication varbinary(max) NOT NULL,
  refresh_token VARCHAR(255) NOT NULL,
  PRIMARY KEY (authentication_id)
);
CREATE TABLE oauth_refresh_token (
  token_id VARCHAR(255) NOT NULL,
  token varbinary(max) NOT NULL,
  authentication varbinary(max) NOT NULL
);
CREATE TABLE oauth_client_details (
    client_id VARCHAR(256) NOT NULL,
    resource_ids VARCHAR(256) NOT NULL,
    client_secret VARCHAR(256) NOT NULL,
    scope VARCHAR(256) NULL,
    authorized_grant_types VARCHAR(256) NOT NULL,
    web_server_redirect_uri VARCHAR(256) NULL,
    authorities VARCHAR(256) NULL,
    access_token_validity INT NULL,
    refresh_token_validity INT NULL,
    additional_information VARCHAR(4096) NULL,
    autoapprove VARCHAR(256) NULL,
    PRIMARY KEY (client_id)
);
CREATE TABLE users (
    USERNAME VARCHAR(50) NOT NULL,
    PASSWORD VARCHAR(500) NOT NULL,
    ENABLED BIT NOT NULL,
    PRIMARY KEY (USERNAME)
);
CREATE TABLE authorities (
    USERNAME VARCHAR(50) NOT NULL,
    AUTHORITY VARCHAR(50) NOT NULL,
    CONSTRAINT USERS_AUTHORITIES FOREIGN KEY (USERNAME) REFERENCES users (USERNAME),
    CONSTRAINT AUTH_USERNAME UNIQUE (USERNAME, AUTHORITY)
);

SQL-Create for IBM DB2

SQL-Create for IBM DB2
CREATE TABLE oauth_access_token (
    token_id VARCHAR(255) NOT NULL,
    token blob NOT NULL,
    authentication_id VARCHAR(255) NOT NULL,
    user_name VARCHAR(50) NOT NULL,
    client_id VARCHAR(255) NOT NULL,
    authentication blob NOT NULL,
    refresh_token VARCHAR(255) NOT NULL,
    PRIMARY KEY (authentication_id)
);
CREATE TABLE oauth_refresh_token (
    token_id VARCHAR(255) NOT NULL,
    token blob NOT NULL,
    authentication blob NOT NULL
);
CREATE TABLE oauth_client_details (
    client_id VARCHAR(256) NOT NULL,
    resource_ids VARCHAR(256) NOT NULL,
    client_secret VARCHAR(256) NOT NULL,
    scope VARCHAR(256) NULL,
    authorized_grant_types VARCHAR(256) NOT NULL,
    web_server_redirect_uri VARCHAR(256) NULL,
    authorities VARCHAR(256) NULL,
    access_token_validity INT NULL,
    refresh_token_validity INT NULL,
    additional_information VARCHAR(4096) NULL,
    autoapprove VARCHAR(256) NULL,
    PRIMARY KEY (client_id)
);
CREATE TABLE users (
    USERNAME VARCHAR(50) NOT NULL,
    PASSWORD VARCHAR(500) NOT NULL,
    ENABLED SMALLINT NOT NULL,
    PRIMARY KEY (USERNAME)
);
CREATE TABLE authorities (
    USERNAME VARCHAR(50) NOT NULL,
    AUTHORITY VARCHAR(50) NOT NULL,
    CONSTRAINT USERS_AUTHORITIES FOREIGN KEY (USERNAME) REFERENCES users (USERNAME),
    CONSTRAINT AUTH_USERNAME UNIQUE (USERNAME, AUTHORITY)
);

Sample configuration

In this example, configuration is explained using RuleManagerApp, RuleManagerService and AuthorizationServer.

The configuration of the OAuth2 security authorization is stored in the property-files and in the tables oauth_client_details, users and authorities. For the actual configuration the understanding of the following constants (sample/default values in bold) is essential:

client_id = rm-client the value of this parameter can be modified by the customer, but it should identify clearly the client accessing te resource to be secured.

resource_id = compass-service
the value of this parameter can be modified by the customer, but it should identify clearly the resource to be secured. In our case this resource is the COMPASS REST API, and as such we use the default value „compass-service“. This value appears in the oauth_client_details table (column resource_ids) and in the configuration file for the RuleManagerService_.

client_secret = rm-client-secret
the parameter client_id identifies the client application. Its value can be chosen freely. In this case the client application is the RuleManagerApp_, and as such by default we use the value „rm-client“. The client_id/ client_secret combination is used to make sure only a valid client application may access the Authorization Server. Therefore, also the password rm-client-secret is free to be modified in your environment. This pair of values has to be known to the client application and the Authorization Server for confirmation. As such, they can be found in the property file of the RuleManagerService and in the oauth_client_details table (column client_id and BCrypt-encoded in the column client_secret)

username = userone

password = userone the parameter username together with its password password identifies the user. Both values can freely be chosen. They have to be known to the client application (property file of the CaseViewer) and to the Authorization Server (users table, where the password is BCrypt-encoded).

Although the username is limited to 50 character, the size of the username should not exceed 20 characters, since the username in the table COMPASS C40_Author is limited to 20 characters. To Login successfull, the username must exist in both tables.

authorized_grant_types = password, refresh_token the parameter grant_type represents the type of authorization. Several types are supported by OAuth2, but in our case the authentication should be done either via password, or via refresh token; therefore this parameter should contain the value „password,refresh_token“. This value can be found only in the oauth_client_details table.

scope = read,write the scope-parameter is currently not used within the COMPASS architecture. It typically contains values like read or write, but it can be chosen freely. We recommend leaving its value at „read,write“. This value is only defined in the oauth_client_details table.

Authorization data in the database

This chapter deals with the configuration of the database tables. The tables oauth_access_token and oauth_refresh_token are managed by the Authorization Server during authentication. Only the other 3 tables have to be prefilled by an administrator:

oauth_client_details
users (optional if used with LDAP-Server, See chapters User details in a LDAP-Server and Authorization data in the database for the RuleManager)
authorities Before the data of the client application (i.e. RuleManagerApp) and user information can be inserted into the tables, sensitive data like client_secret (Authorization password for the client application) and `password* (Password of the user) have to be encoded. For this purpose the Spring Security Framework suggests encrypting the string with BCrypt. In the following examples, the default values from chapter 2.2 are used. The passwords are all BCrypt-encoded.

User details in a LDAP-Server

In case a LDAP-Server is used to store the user credentials, the user table is not needed. The Authorization Server currently supports the following hash methods for passwords: • SHA • MD5 • Plaintext One of the above hash method has to be defined within the user entry in the LDAP-Server (For configuration of the authorization server see LDAP Related Properties).

SQL-Inserts for MySQL and DB2

Client-Details:

INSERT INTO oauth_client_details (resource_ids, client_id, client_secret, scope, authorized_grant_types, access_token_validity, refresh_token_validity) VALUES ('compass-service', 'case-viewer',  '$2a$10$dbU2S.ehdNHKQFLjrmOofORpd7NEfjUvXEBubGKCfvDklsHcBIhYy', 'read,write', 'password,refresh_token', 300, 600);

Remark: the column 'client_secret' accepts the BCrypt-encoded value: „$2a$10$dbU2S.ehdNHKQFLjrmOofORpd7NEfjUvXEBubGKCfvDklsHcBIhYy“

The value has been generated from case-viewer-secret.

User details:

INSERT INTO users (USERNAME, PASSWORD, ENABLED) VALUES ('admin', '$2a$10$HqXnMW9nm8p9fXVlLalu6OafEXD5i9q79GUw7RfIm2sBflNud2MpO', true);
Remark: the column „PASSWORD“ accepts the BCrypt-encoded value: „$2a$10$HqXnMW9nm8p9fXVlLalu6OafEXD5i9q79GUw7RfIm2sBflNud2MpO“

The value has been generated from admin-password.

Depending on the used version of DB2, Boolean values are handled differently and might need to be inserted accordingly. The Boolean can also be added as an Integer value:

INSERT INTO users (USERNAME, PASSWORD, ENABLED) VALUES ('admin', '$2a$10$HqXnMW9nm8p9fXVlLalu6OafEXD5i9q79GUw7RfIm2sBflNud2MpO', 1);

Authorities for the user:

INSERT INTO authorities (USERNAME, AUTHORITY) VALUES ('admin', 'EXECUTE');

Authorization data in the database for the RuleManager

The RuleManagerApp is deployed with two default users userone and usertwo (with passwords userone and usertwo). Before the data of the client application (RuleManagerApp) and user information can be inserted into the tables, sensitive data like client_secret (Authorization password for the RuleManagerApp) and password (Password of the user) have to be encoded via BCrypt. Please adapt the statements to the user/password combinations assigned to your RuleManagerApp users.

SQL-Inserts for MySQL and DB2

Client-Details

INSERT INTO oauth_client_details (resource_ids, client_id, client_secret, scope, authorized_grant_types, access_token_validity, refresh_token_validity) VALUES ('compass-service', 'rm-client',  '$2a$10$LhVNoIVFDhmUzq87vcfB0O6vfGNhhLyxY5l1Q6xu/I1s4lEqZrosq', 'read,write', 'password,refresh_token', 300, 600);

Remark: the column client_secret accepts the BCrypt-encoded value generated from rm-client -secret.

User-Details

INSERT INTO users (USERNAME, PASSWORD, ENABLED) VALUES ('userone', '$2a$10$7CseykqiGFJT.Ulo9P0VB.8l1.WK.xjKkTU/GsK.Nr.SmdEIsT7eq', true);
INSERT INTO users (USERNAME, PASSWORD, ENABLED) VALUES ('usertwo', ' $2a$10$.f5cxF5opkEc8Ooj86J2IeZ65aM06LZhEhw3/z262C59AXtkPyQUi', true);

Remark: the column „PASSWORD“ accepts the BCrypt-encoded values generated from the passwords userone and usertwo.

Authorities for the user

INSERT INTO authorities (USERNAME, AUTHORITY) VALUES ('userone', 'EXECUTE');
INSERT INTO authorities (USERNAME, AUTHORITY) VALUES ('usertwo', 'EXECUTE');

Properties

General Properties

There are two property- / yaml-files related to the security architecture: in case of the RuleMnagerApp, these are RuleManagerService.properties and config_authorization.yaml:

Usually, these files can be found in a subdirectory COMPASSconfig: (since the location of the configuration can be changed by the administrator, the location of said files may vary depending on the individual setup of COMPASS).

COMPASSConfig/CompassAuthorization.yaml COMPASSconfig/RuleManagerService.properties

Table 1. Properties of CompassAuthorization
Property	Explanation
server:port:	Port on which Authorization Server is listening
server:servlet:contextPath	The context path of the Authorization Server
logging:level:org:springframework	Possible values: ERROR, WARN, INFO, DEBUG, TRACE
spring:datasource:url	JDBC-URL to access the datasource
spring:datasource:username	database-user
spring:datasource:password	password for database-user
spring:datasource:driverClassName	class-name of the JDBC driver
spring:datasource:jdbcUrl	constant: Content of spring:datasource:url
spring:datasource:jdbcUrl	constant: Content of spring:datasource:url
spring:datasource:minimumIdle	minimum number of idle connections maintained by HikariCP in a connection pool
spring:datasource:maximumPoolSize	maximum pool size
spring:datasource:idleTimeOut	maximum idle time for connection
spring:datasource:maxLifetime	maximum lifetime in milliseconds of a connection in the pool after it is closed
spring:datasource:poolName	name of the connection pool
spring:datasource:connectionTimeout	timeout for connection
spring:datasource:type	constant: Type of datasource
spring:jpa:database-platform	Hibernate dialect for database
security:connectionPoolEnabled	true \| false
security:connectionPoolEnabled	true \| false
cors:policy:enabled	true \| false
cors:allowed:crossorigin:urls	URLS which are allowed for cross origin requests
cors:allowed:crossorigin:methods	Methods which are allowed for cross origin requests
cors:allowed:crossorigin:header	HTTP header which are allowed, all headers allowed = "*"
cors:allowed:crossorigin:allowecredentials	true \| false whether credentials are allowed over cross origins
cors:allowed:crossorigin:maxAge	maximum age of validity of the preflight requests

Table 2. LDAP R elatedProperties of CompassAuthorization
Property	Explanation
ldap:enabled	true \| false
ldap:url	URL of the LDAP server
ldap:root:user:dnPatterns	Pattern for distinguished names
ldap:root:user:searchBase	LDAP search base
ldap:root:user:searchFilter	LDAP search filter
securityx.token.Endpoint.retryEnabled	true \|false, default=false
securityx.token.Endpoint.numberOfRetries	Number of retries per request, default=4
securityx.token.Endpoint.retryWaitingTime	Time between retries in milliseconds. Default = 1000 ms

Example

server:
  port: 8085
  servlet:
    contextPath: /CompassAuthorization
logging:
  level:
    org:
      springframework: DEBUG
spring:
  datasource:
    url: jdbc:mariadb://localhost:3306/hds60_compass_security
    username: UW_POS
    password: UW_POS
    # Driver class name and the below properties are required for connection pooling
    driverClassName: org.mariadb.jdbc.Driver
    #driverClassName: com.ibm.db2.jcc.DB2Driver
    jdbcUrl: ${spring.datasource.url}
    minimumIdle: 5
    maximumPoolSize: 22
    idleTimeout: 650000
    poolName: SpringBootJPAHikariCP
    maxLifetime: 550000
    connectionTimeout: 30000
    type: com.zaxxer.hikari.HikariDataSource
  # If DB2 is used, the database-platform needs to be defined
  jpa:
    database-platform: org.hibernate.dialect.MariaDB103Dialect

ldap:
  enabled: false
  url: ldap://10.10.10.10:389/dc=company,dc=com
  root:
    user: cn=ldapadm,dc=company,dc=com
    password: gen2lhcs
  user:
    dnPatterns: cn={0},ou=User
    searchBase: ou=User
    searchFilter: cn={0}
  group:
    searchBase: ou=Group
    searchFilter: member={0}

# Activate the below property to enable the Hikari Connection pooling
security:
  connectionPoolEnabled: false

cors:
    policy:
        enabled: true
    allowed:
        crossorigin:
            urls: http://somehost.somedomain.com:8085,http://somehost.somedomain.com:8080,http://somehost.somedomain.com:8070,http://localhost:8085,http://localhost:8080,http://localhost:8070
            methods: GET,POST,PUT,OPTIONS,HEAD,DELETE
            header: "*"
            allowcredentials: true
            maxage: 600

Deployment & Usage

Deployment

The Authorization Server is optional to the standard deployment of COMPASS 6. It may be started as a Spring Boot application, alternatively it can be depoyed in any servlet container supporting Servlet API 3.0 or better.

Running as Spring Boot application

Authorization Server can be started with the following command:

Syntax

java -Xmx512M -cp lib\CompassAuthorization.war;[jdbc-driver] \\
org.springframework.boot.loader.WarLauncher \\
--spring.config.location=[loation of configuraion-file]

Table 3. Parameters
Parameter	Explanation
[jdbc-driver]	JDBC-driver incl. paath
[loation of configuraion-file]	location of configuraion-file (see Properties)

Example

java -Xmx512M -cp lib\CompassAuthorization.war;lib\mariadb-java-client-2.7.3.jar \\
org.springframework.boot.loader.WarLauncher \\
--spring.config.location./config/config_authorization.yaml

Deployment Within Servlet Container

Since Authorization Server comes as a war-file, it can be deployed in any servlet container: Please refer to the documentation of your servlet container about how to deploy a servlet.

There are multiple ways to configure the location of the configuration file (see Properties). A generic option working in every servlet container i to create a deployment descriptor for Authorization Server and specify the location via an environment entry which is picked up by Spring Boot during startup:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
		  http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">
    <!-- In web.xml, the location of the configuration file config_authorization.yaml (spring.congig.location)
    can be defined in case you are running JBoss / WildFly or Apache Tomcat.

    Alternatively, spring.config.location can also be passed as Java-property
    -Dspring.config.location=file:///${CATALINA_HOME}/COMPASSConfig/config_authorization.yaml
    or, alternatively, pass it as a JAVA-Property, i.e. via CLI:

    -Dspring.config.location=file:///${jboss.home.dir}/COMPASSConfig/config_authorization.yaml
    -->

    <env-entry>
        <env-entry-name>
            spring.config.location
        </env-entry-name>
        <env-entry-type>
            java.lang.String
        </env-entry-type>
        <env-entry-value>
            file:${jboss.home.dir}/COMPASSConfig/config_authorization.yaml
        </env-entry-value>
    </env-entry>
</web-app>

Using the OAuth2-API

In case a COMPASS-customer has developed their own implementation of a client (i.e. Screenbuilder-client), the client can interface with Authorization Server using the API-call below, which will return a bearer-token (see Example: Compass-REST security with RuleManagerApp)

Syntax

POST http://[host]:[port]/CompassAuthorization/oauth/token?grant_type=password&scope=read%20write&username=[username]&password=[password]&client_id=[client-id]&client_secret=[client-secret]

Table 4. Parameter
Parameter	Explanation
[username]	a user name
[password]	a password
[client-id]	a client-id (see OAuth2)
[client-id]	a client-id (see OAuth2)

Example

POST http://localhost:8085/CompassAuthorization/oauth/token?grant_type=password&scope=read%20write&username=userone&password=userone&client_id=rm-client&client_secret=rm-client-secret

The above call will return the bearer-token, which then needs to be passed with each request accessing a secured device as a value for the HTTP Header Authorization:

Example

GET http://localhost:8086/CompassService/version

Table 5. Header
Header-Name	Content
Authorization	Bearer HK4xTssNXmFsFM0vJYs15hlXCQc